<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /fasttmp/mkdist-qt-4.3.5-1211793125/qtopia-core-opensource-src-4.3.5/src/qt3support/network/q3dns.cpp -->
<head>
  <title>Qt 4.3: Q3Dns Class Reference</title>
  <link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
<td width="1">&nbsp;&nbsp;</td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a>&nbsp;&middot; <a href="classes.html"><font color="#004faf">All&nbsp;Classes</font></a>&nbsp;&middot; <a href="mainclasses.html"><font color="#004faf">Main&nbsp;Classes</font></a>&nbsp;&middot; <a href="groups.html"><font color="#004faf">Grouped&nbsp;Classes</font></a>&nbsp;&middot; <a href="modules.html"><font color="#004faf">Modules</font></a>&nbsp;&middot; <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">Q3Dns Class Reference<br /><sup><sup>[<a href="qt3support.html">Qt3Support</a> module]</sup></sup></h1>
<p>The Q3Dns class provides asynchronous DNS lookups. <a href="#details">More...</a></p>
<pre> #include &lt;Q3Dns&gt;</pre><p><b>This class is part of the Qt 3 support library.</b> It is provided to keep old source code working. We strongly advise against using it in new code. See <a href="porting4.html#qdns">Porting to Qt 4</a> for more information.</p>
<p>Inherits <a href="qobject.html">QObject</a>.</p>
<ul>
<li><a href="q3dns-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h3>Public Types</h3>
<ul>
<li><div class="fn"/>enum <b><a href="q3dns.html#RecordType-enum">RecordType</a></b> { None, A, Aaaa, Mx, ..., Txt }</li>
</ul>
<a name="public-functions"></a>
<h3>Public Functions</h3>
<ul>
<li><div class="fn"/><b><a href="q3dns.html#Q3Dns">Q3Dns</a></b> ()</li>
<li><div class="fn"/><b><a href="q3dns.html#Q3Dns-2">Q3Dns</a></b> ( const QString &amp; <i>label</i>, RecordType <i>rr</i> = A )</li>
<li><div class="fn"/><b><a href="q3dns.html#Q3Dns-3">Q3Dns</a></b> ( const QHostAddress &amp; <i>address</i>, RecordType <i>rr</i> = Ptr )</li>
<li><div class="fn"/>virtual <b><a href="q3dns.html#dtor.Q3Dns">~Q3Dns</a></b> ()</li>
<li><div class="fn"/>Q3ValueList&lt;QHostAddress&gt; <b><a href="q3dns.html#addresses">addresses</a></b> () const</li>
<li><div class="fn"/>QString <b><a href="q3dns.html#canonicalName">canonicalName</a></b> () const</li>
<li><div class="fn"/>QStringList <b><a href="q3dns.html#hostNames">hostNames</a></b> () const</li>
<li><div class="fn"/>bool <b><a href="q3dns.html#isWorking">isWorking</a></b> () const</li>
<li><div class="fn"/>QString <b><a href="q3dns.html#label">label</a></b> () const</li>
<li><div class="fn"/>Q3ValueList&lt;MailServer&gt; <b><a href="q3dns.html#mailServers">mailServers</a></b> () const</li>
<li><div class="fn"/>QStringList <b><a href="q3dns.html#qualifiedNames">qualifiedNames</a></b> () const</li>
<li><div class="fn"/>RecordType <b><a href="q3dns.html#recordType">recordType</a></b> () const</li>
<li><div class="fn"/>Q3ValueList&lt;Server&gt; <b><a href="q3dns.html#servers">servers</a></b> () const</li>
<li><div class="fn"/>virtual void <b><a href="q3dns.html#setLabel">setLabel</a></b> ( const QString &amp; <i>label</i> )</li>
<li><div class="fn"/>virtual void <b><a href="q3dns.html#setLabel-2">setLabel</a></b> ( const QHostAddress &amp; <i>address</i> )</li>
<li><div class="fn"/>virtual void <b><a href="q3dns.html#setRecordType">setRecordType</a></b> ( RecordType <i>rr</i> = A )</li>
<li><div class="fn"/>QStringList <b><a href="q3dns.html#texts">texts</a></b> () const</li>
</ul>
<ul>
<li><div class="fn"/>29 public functions inherited from <a href="qobject.html#public-functions">QObject</a></li>
</ul>
<a name="signals"></a>
<h3>Signals</h3>
<ul>
<li><div class="fn"/>void <b><a href="q3dns.html#resultsReady">resultsReady</a></b> ()</li>
</ul>
<ul>
<li><div class="fn"/>1 signal inherited from <a href="qobject.html#signals">QObject</a></li>
</ul>
<h3>Additional Inherited Members</h3>
<ul>
<li><div class="fn"/>1 property inherited from <a href="qobject.html#properties">QObject</a></li>
<li><div class="fn"/>1 public slot inherited from <a href="qobject.html#public-slots">QObject</a></li>
<li><div class="fn"/>5 static public members inherited from <a href="qobject.html#static-public-members">QObject</a></li>
<li><div class="fn"/>7 protected functions inherited from <a href="qobject.html#protected-functions">QObject</a></li>
</ul>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The Q3Dns class provides asynchronous DNS lookups.</p>
<p>Both Windows and Unix provide synchronous DNS lookups; Windows provides some asynchronous support too. At the time of writing neither operating system provides asynchronous support for anything other than hostname-to-address mapping.</p>
<p>Q3Dns rectifies this shortcoming, by providing asynchronous caching lookups for the record types that we expect modern GUI applications to need in the near future.</p>
<p>The class is <i>not</i> straightforward to use (although it is much simpler than the native APIs); <a href="q3socket.html">Q3Socket</a> provides much easier to use TCP connection facilities. The aim of Q3Dns is to provide a correct and small API to the DNS and nothing more. (We use &quot;correctness&quot; to mean that the DNS information is correctly cached, and correctly timed out.)</p>
<p>The API comprises a constructor, functions to set the DNS node (the domain in DNS terminology) and record type (<a href="q3dns.html#setLabel">setLabel</a>() and <a href="q3dns.html#setRecordType">setRecordType</a>()), the corresponding get functions, an <a href="q3dns.html#isWorking">isWorking</a>() function to determine whether Q3Dns is working or reading, a <a href="q3dns.html#resultsReady">resultsReady</a>() signal and query functions for the result.</p>
<p>There is one query function for each <a href="q3dns.html#RecordType-enum">RecordType</a>, namely <a href="q3dns.html#addresses">addresses</a>(), <a href="q3dns.html#mailServers">mailServers</a>(), <a href="q3dns.html#servers">servers</a>(), <a href="q3dns.html#hostNames">hostNames</a>() and <a href="q3dns.html#texts">texts</a>(). There are also two generic query functions: <a href="q3dns.html#canonicalName">canonicalName</a>() returns the name you'll presumably end up using (the exact meaning of this depends on the record type) and <a href="q3dns.html#qualifiedNames">qualifiedNames</a>() returns a list of the fully qualified names <a href="q3dns.html#label">label</a>() maps to.</p>
<p>See also <a href="q3socket.html">Q3Socket</a>.</p>
<hr />
<h2>Member Type Documentation</h2>
<h3 class="fn"><a name="RecordType-enum"></a>enum Q3Dns::RecordType</h3>
<p>This enum type defines the record types <a href="q3dns.html">Q3Dns</a> can handle. The DNS provides many more; these are the ones we've judged to be in current use, useful for GUI programs and important enough to support right away:</p>
<p><table border="1" cellpadding="2" cellspacing="1" width="100%">
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
<tr><td valign="top"><tt>Q3Dns::None</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">No information. This exists only so that <a href="q3dns.html">Q3Dns</a> can have a default.</td></tr>
<tr><td valign="top"><tt>Q3Dns::A</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">IPv4 addresses. By far the most common type.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Aaaa</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">IPv6 addresses. So far mostly unused.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Mx</tt></td><td align="center" valign="top"><tt>3</tt></td><td valign="top">Mail eXchanger names. Used for mail delivery.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Srv</tt></td><td align="center" valign="top"><tt>4</tt></td><td valign="top">SeRVer names. Generic record type for finding servers. So far mostly unused.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Cname</tt></td><td align="center" valign="top"><tt>5</tt></td><td valign="top">Canonical names. Maps from nicknames to the true name (the canonical name) for a host.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Ptr</tt></td><td align="center" valign="top"><tt>6</tt></td><td valign="top">name PoinTeRs. Maps from IPv4 or IPv6 addresses to hostnames.</td></tr>
<tr><td valign="top"><tt>Q3Dns::Txt</tt></td><td align="center" valign="top"><tt>7</tt></td><td valign="top">arbitrary TeXT for domains.</td></tr>
</table></p>
<p>We expect that some support for the <a href="http://www.rfc-editor.org/rfc/rfc2535.txt">RFC 2535</a> extensions will be added in future versions.</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="Q3Dns"></a>Q3Dns::Q3Dns ()</h3>
<p>Constructs a DNS query object with invalid settings for both the label and the search type.</p>
<h3 class="fn"><a name="Q3Dns-2"></a>Q3Dns::Q3Dns ( const <a href="qstring.html">QString</a> &amp; <i>label</i>, <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = A )</h3>
<p>Constructs a DNS query object that will return record type <i>rr</i> information about <i>label</i>.</p>
<p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p>
<p><i>rr</i> defaults to <tt>A</tt>, IPv4 addresses.</p>
<h3 class="fn"><a name="Q3Dns-3"></a>Q3Dns::Q3Dns ( const <a href="qhostaddress.html">QHostAddress</a> &amp; <i>address</i>, <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = Ptr )</h3>
<p>Constructs a DNS query object that will return record type <i>rr</i> information about host address <i>address</i>. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the <tt>Ptr</tt> record type (e.g&#x2e; if you want to look up a hostname for a given address).</p>
<p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p>
<p><i>rr</i> defaults to <tt>Ptr</tt>, that maps addresses to hostnames.</p>
<h3 class="fn"><a name="dtor.Q3Dns"></a>Q3Dns::~Q3Dns ()&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>Destroys the DNS query object and frees its allocated resources.</p>
<h3 class="fn"><a name="addresses"></a><a href="q3valuelist.html">Q3ValueList</a>&lt;<a href="qhostaddress.html">QHostAddress</a>&gt; Q3Dns::addresses () const</h3>
<p>Returns a list of the addresses for this name if this <a href="q3dns.html">Q3Dns</a> object has a <a href="q3dns.html#recordType">recordType</a>() of <a href="q3dns.html#RecordType-enum">Q3Dns::A</a> or <a href="q3dns.html#RecordType-enum">Q3Dns::Aaaa</a> and the answer is available; otherwise returns an empty list.</p>
<p>As a special case, if <a href="q3dns.html#label">label</a>() is a valid numeric IP address, this function returns that address.</p>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> Q3ValueList&lt;QHostAddress&gt; list = myDns.addresses();
 Q3ValueList&lt;QHostAddress&gt;::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<h3 class="fn"><a name="canonicalName"></a><a href="qstring.html">QString</a> Q3Dns::canonicalName () const</h3>
<p>Returns the canonical name for this DNS node. (This works regardless of what <a href="q3dns.html#recordType">recordType</a>() is set to.)</p>
<p>If the canonical name isn't known, this function returns a null string.</p>
<p>The canonical name of a DNS node is its full name, or the full name of the target of its CNAME. For example, if l.trolltech.com is a CNAME to lillian.troll.no, and the search path for <a href="q3dns.html">Q3Dns</a> is &quot;trolltech.com&quot;, then the canonical name for all of &quot;lillian&quot;, &quot;l&quot;, &quot;lillian.troll.no.&quot; and &quot;l.trolltech.com&quot; is &quot;lillian.troll.no.&quot;&#x2e;</p>
<h3 class="fn"><a name="hostNames"></a><a href="qstringlist.html">QStringList</a> Q3Dns::hostNames () const</h3>
<p>Returns a list of host names if the record type is <tt>Ptr</tt>.</p>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> QStringList list = myDns.hostNames();
 QStringList::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<h3 class="fn"><a name="isWorking"></a>bool Q3Dns::isWorking () const</h3>
<p>Returns true if <a href="q3dns.html">Q3Dns</a> is doing a lookup for this object (i.e&#x2e; if it does not already have the necessary information); otherwise returns false.</p>
<p><a href="q3dns.html">Q3Dns</a> emits the <a href="q3dns.html#resultsReady">resultsReady</a>() signal when the status changes to false.</p>
<h3 class="fn"><a name="label"></a><a href="qstring.html">QString</a> Q3Dns::label () const</h3>
<p>Returns the domain name for which this object returns information.</p>
<p>See also <a href="q3dns.html#setLabel">setLabel</a>().</p>
<h3 class="fn"><a name="mailServers"></a><a href="q3valuelist.html">Q3ValueList</a>&lt;MailServer&gt; Q3Dns::mailServers () const</h3>
<p>Returns a list of mail servers if the record type is <tt>Mx</tt>. The class Q3Dns::MailServer contains the following public variables:</p>
<ul>
<li><a href="qstring.html">QString</a> <a href="q3dns-mailserver.html#name-var">Q3Dns::MailServer::name</a></li>
<li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-mailserver.html#priority-var">Q3Dns::MailServer::priority</a></li>
</ul>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> Q3ValueList&lt;Q3Dns::MailServer&gt; list = myDns.mailServers();
 Q3ValueList&lt;Q3Dns::MailServer&gt;::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<h3 class="fn"><a name="qualifiedNames"></a><a href="qstringlist.html">QStringList</a> Q3Dns::qualifiedNames () const</h3>
<p>Returns a list of the fully qualified names <a href="q3dns.html#label">label</a>() maps to.</p>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> QStringList list = myDns.qualifiedNames();
 QStringList::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<h3 class="fn"><a name="recordType"></a><a href="q3dns.html#RecordType-enum">RecordType</a> Q3Dns::recordType () const</h3>
<p>Returns the record type of this DNS query object.</p>
<p>See also <a href="q3dns.html#setRecordType">setRecordType</a>() and <a href="q3dns.html#RecordType-enum">RecordType</a>.</p>
<h3 class="fn"><a name="resultsReady"></a>void Q3Dns::resultsReady ()&nbsp;&nbsp;<tt> [signal]</tt></h3>
<p>This signal is emitted when results are available for one of the <a href="q3dns.html#qualifiedNames">qualifiedNames</a>().</p>
<h3 class="fn"><a name="servers"></a><a href="q3valuelist.html">Q3ValueList</a>&lt;Server&gt; Q3Dns::servers () const</h3>
<p>Returns a list of servers if the record type is <tt>Srv</tt>. The class Q3Dns::Server contains the following public variables:</p>
<ul>
<li><a href="qstring.html">QString</a> <a href="q3dns-server.html#name-var">Q3Dns::Server::name</a></li>
<li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#priority-var">Q3Dns::Server::priority</a></li>
<li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#weight-var">Q3Dns::Server::weight</a></li>
<li><a href="qtglobal-qt3.html#Q_UINT16-typedef">Q_UINT16</a> <a href="q3dns-server.html#port-var">Q3Dns::Server::port</a></li>
</ul>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> Q3ValueList&lt;Q3Dns::Server&gt; list = myDns.servers();
 Q3ValueList&lt;Q3Dns::Server&gt;::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<h3 class="fn"><a name="setLabel"></a>void Q3Dns::setLabel ( const <a href="qstring.html">QString</a> &amp; <i>label</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>Sets this DNS query object to query for information about <i>label</i>.</p>
<p>This does not change the <a href="q3dns.html#recordType">recordType</a>(), but its <a href="q3dns.html#isWorking">isWorking</a>() status will probably change as a result.</p>
<p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p>
<p>See also <a href="q3dns.html#label">label</a>().</p>
<h3 class="fn"><a name="setLabel-2"></a>void Q3Dns::setLabel ( const <a href="qhostaddress.html">QHostAddress</a> &amp; <i>address</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>Sets this DNS query object to query for information about the host address <i>address</i>. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with the <tt>Ptr</tt> record type (e.g&#x2e; if you want to look up a hostname for a given address).</p>
<h3 class="fn"><a name="setRecordType"></a>void Q3Dns::setRecordType ( <a href="q3dns.html#RecordType-enum">RecordType</a> <i>rr</i> = A )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>Sets this object to query for record type <i>rr</i> records.</p>
<p>The DNS lookup is started the next time the application enters the event loop. When the result is found the signal <a href="q3dns.html#resultsReady">resultsReady</a>() is emitted.</p>
<p>See also <a href="q3dns.html#recordType">recordType</a>() and <a href="q3dns.html#RecordType-enum">RecordType</a>.</p>
<h3 class="fn"><a name="texts"></a><a href="qstringlist.html">QStringList</a> Q3Dns::texts () const</h3>
<p>Returns a list of texts if the record type is <tt>Txt</tt>.</p>
<p>Note that if you want to iterate over the list, you should iterate over a copy, e.g&#x2e;</p>
<pre> QStringList list = myDns.texts();
 QStringList::Iterator it = list.begin();
 while( it != list.end() ) {
     myProcessing( *it );
     ++it;
 }</pre>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright &copy; 2008 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt 4.3.5</div></td>
</tr></table></div></address></body>
</html>
